/**************************************************************************
 *         Copyright(c) 2007 by Sunplus mMedia  Technology Co., Ltd.       *
 *                                                                         *
 *  This software is copyrighted by and is the property of Sunplus mMedia  *
 *  Technology Co., Ltd. All rights are reserved by Sunplus mMedia Techno- *
 *  logy Co., Ltd. This software may only be used in accordance with the   *
 *  corresponding license agreement. Any unauthorized use, duplication,    *
 *  distribution, or disclosure of this software is expressly forbidden.   *
 *                                                                         *
 *  This Copyright notice "M U S T" not be removed or modified without     *
 *  prior written consent of Sunplus mMedia Technology  Co., Ltd.          *
 *                                                                         *
 *  Sunplus mMedia Technology Co., Ltd. reserves the right to modify this  *
 *  software without notice.                                               *
 *                                                                         *
 *  Sunplus mMedia Technology Co., Ltd.                                    *
 *  19-1, Innovation First Road, Science-Based Industrial Park,            *
 *  Hsin-Chu, Taiwan, R.O.C.                                               *
 *                                                                         *
 **************************************************************************/
#ifndef __SP1K_PV_API_H__
#define __SP1K_PV_API_H__

/** \file sp1k_pv_api.h
 * @brief		Spca1528 preview related interface
 */

#include "pv_api.h"
#include "sp1k_def.h"

/**************************************************************************
 *                           C O N S T A N T S                            *
 **************************************************************************/

/**************************************************************************
 *                              M A C R O S                               *
 **************************************************************************/
#ifdef SP1K_DOXY_GEN
/**
 * @fn void sp1kPvZoomSet(UINT8 pvStart, UINT16 factor, UINT8 pbFreeze)
 * @brief	specify preview zoom factor, Range is from 100(1.0x)  to 400(4.0x)
 * @param[in] pvStart	 specify if to wait zoom update signal
 *\n                              0: wait until preview zoom update ready. In general, 0 should be set for repeat zoom.
 *\n                              1: do not wait any zoom update ready signal                               
 * @param[in] factor      zoom factor. range is 100 to 400
 * @param[in] pbfreeze	 not used
 * @retval none
 * @see sp1kPrevewSet()
 */
void sp1kPvZoomSet(UINT8 pvStart, UINT16 factor, UINT8 pbFreeze);

/**
 * @fn void sp1kPvSizeGet(UINT16 *phSize, UINT16 *pvSize);
 * @brief	obtain preview buffer dimension. The unit is pixel.
 * @param[out] phSize	 Pointer to the buffer containing the image width
 * @param[out] pvSize	 Pointer to the buffer containing the image height
 * @retval none
 */
void sp1kPvSizeGet(UINT16 *phSize, UINT16 *pvSize);

/**
 * @fn UINT32 sp1kPvFreeBuffGet(void)
 * @brief	obtain the starting physical address of system free buffer. The unit is word.
 * @retval the statring of system free physical buffer address in word unit
 */
UINT32 sp1kPvFreeBuffGet(void);

#else
#define sp1kPvZoomSet      pvZoomSet
#define sp1kPvSizeGet      pvSizeGet
#define sp1kPvFreeBuffGet  pvFreeBuffGet
#endif

/**************************************************************************
 *                          D A T A    T Y P E S                          *
 **************************************************************************/

/**************************************************************************
 *                         G L O B A L    D A T A                         *
 **************************************************************************/

/**************************************************************************
 *                 E X T E R N A L    R E F E R E N C E S                 *
 **************************************************************************/

/**************************************************************************
 *               F U N C T I O N    D E C L A R A T I O N S               *
 **************************************************************************/
/**
 * @fn sp1kFrontInit(void)
 * @brief	Init front setting.  The function must be called before the system switch to peview mode
 * @retval none
 * @see sp1kCDSPInit(), sp1kPrevewSet()
 */
void sp1kFrontInit(void);

/**
 * @fn UINT8 sp1kPrevewSet(UINT16 vidMode, UINT16 pvWidth, UINT16 pvHeight, UINT16 fact, UINT8 pbFreeze)
 * @brief	Entering from other mode to still or video preview mode
 * @param[in] vidMode	 Specifies still  or video preview mode
 *\n                     0: Still preview mode
 *\n                     1. Video preview mode
 * @param[in] pvWidth	 preview buffer width
 *\n                     still preview buffer is 320x240 by system default. 
 *\n                     video preview buffer will be 320x240 or 640x480 depends the size of video you are recording
 *\n                     caller needs to refer to system DRAM map if alter preview dimension is really necessary
 * @param[in] pvHeight	 preview buffer height
 * @param[in] fact         zoom factor. range is 100 to 400
 * @param[in] pbfreeze	 specify if to toggle preview buffer immediately. sp1kPrevewUnfreeze() can be called later to trigger the toggle
 *\n                     0: show preview buffer immediately
 *\n                     1: preview will not show immediately until sp1kPrevewUnfreeze() is called.                                  
 * @retval error code -  success: 0, fail: 1
 * @see sp1kPrevewUnfreeze()
 */
UINT8 sp1kPrevewSet(UINT16 vidMode, UINT16 pvWidth,UINT16 pvHeight, UINT16 fact, UINT8 pbfreeze);

/**
 * @fn void sp1kCDSPInit(void)
 * @brief	Initialize cdsp relative settings. The function must be called before the system switch to peview mode
 * @retval none
 * @see sp1kPrevewUnfreeze()
 */
void sp1kCDSPInit(void);

/**
 * @fn void sp1kPrevewUnfreeze(void)
 * @brief Unfreeze preview. The function ususally needs to be called if the last paramater of sp1kPrevewSet() is specified as "freeze".
 * @retval none
 */
void  sp1kPrevewUnfreeze(void);

#endif //__SP1K_PV_API_H__

